Linux Cubed Series 2: Applications

home *** CD-ROM | disk | FTP | other *** search

/ Linux Cubed Series 2: Applications / Linux Cubed Series 2 - Applications.iso / editors / emacs / xemacs / xemacs-1.006 / xemacs-1 / lib / xemacs-19.13 / info / ediff.info-1 < prev next >

Wrap

GNU Info File | 1995-09-01 | 46.9 KB | 1,044 lines

This is Info file ../info/ediff.info, produced by Makeinfo-1.63 from the input file ediff.texi. This file documents Ediff, a comprehensive visual interface to Unix `diff' and `patch' utilities. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. File: ediff.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir) * Menu: * Introduction:: About Ediff. * Major Entry Points:: How to use Ediff. * Commands:: Ediff commands. * Registry of Ediff Sessions:: Keeping track of multiple Ediff sessions. * Session Groups:: Comparing and merging directories. * Remote and Compressed Files:: You may want to know about this. * Customization:: How to make Ediff work the way YOU want. * Credits:: Thanks to those who helped. * Index:: File: ediff.info, Node: Introduction, Next: Major Entry Points, Prev: Top, Up: Top Introduction ************ Ediff provides a convenient way for merging and comparing pairs (or triples) of files and buffers. The files being compared, file-A, file-B, and file-C (if applicable) are shown in separate windows (side by side, one above the another, or in separate frames), and the differences are highlighted as you step through them. You can also copy difference regions from one buffer to another (and recover old differences if you change your mind). Another powerful feature is the ability to merge a pair of files into a third buffer. Merging with an ancestor file is also supported. Furthermore, Ediff is equipped with directory-level capabilities that allow the user to conveniently launch browsing or merging sessions on groups of files in two (or three) different directories. In addition, Ediff can apply a patch to a file and then let you step though both files, the patched and the original one, simultaneously, difference-by-difference. You can even apply a patch right out of a mail buffer, i.e., patches received by mail don't even have to be saved. Since Ediff lets you copy differences between buffers, you can, in effect, apply patches selectively (i.e., you can copy a difference region from `file_orig' to `file', thereby undoing any particular patch that you don't like). Unfortunately, Ediff still doesn't understand multi-file patches--this requires further work (volunteers needed!). Ediff is aware of version control, which lets the user compare files with their older versions. Ediff also works with remote and compressed files, automatically ftp-ing them over and uncompressing them. *Note Remote and Compressed Files::, for details. This package builds upon ideas borrowed from `emerge.el' and several Ediff's routines are adaptations from that package. Although Ediff subsumes `emerge.el' in its functionality, much of that functionality of Ediff is influenced by `emerge.el'. The implementation and the interface are, of course, drastically different. File: ediff.info, Node: Major Entry Points, Next: Commands, Prev: Introduction, Up: Top Major Entry Points ****************** Ediff can be invoked interactively using the following functions, which can be run either from the minibuffer or from the menu bar. In the menu bar, all Ediff's entry points belong to three submenus of the `Tools' menu: `Compare,' `Merge,' and `Apply Patch.' You don't have to remember these entry points, if Ediff is invoked via the menu bar. `ediff-files' `ediff' Compare two files. `ediff-buffers' Compare two buffers. `ediff-files3' `ediff3' Compare three files. `ediff-buffers3' Compare three buffers. `ediff-directories' `edirs' Compare files common to two directories. `ediff-directories3' `edirs3' Compare files common to three directories. `ediff-directory-revisions' `edir-revisions' Compare versions of files in a given directory. Ediff selects only the files that are under version control. `ediff-merge-directory-revisions' `edir-merge-revisions' Merge versions of files in a given directory. Ediff selects only the files that are under version control. `ediff-merge-directory-revisions-with-ancestor' `edir-merge-revisions-with-ancestor' Merge versions of files in a given directory using other versions as ancestors. Ediff selects only the files that are under version control. `ediff-windows-wordwise' Compare windows word-by-word. `ediff-windows-linewise' Compare windows line-by-line. `ediff-regions-wordwise' Compare regions word-by-word. `ediff-regions-linewise' Compare regions line-by-line. `ediff-revision' Compare versions of current buffer, if the buffer is visiting a file under version control. `ediff-patch-file' `epatch' Patch file then compare. At present, doesn't understand multi-file patches. `ediff-patch-buffer' `epatch-buffer' Patch buffer then compare. `ediff-merge-files' `ediff-merge' Merge two files. `ediff-merge-files-with-ancestor' `ediff-merge-with-ancestor' Same but with ancestor. `ediff-merge-buffers' Merge two buffers. `ediff-merge-buffers-with-ancestor' Same but with ancestor. `ediff-merge-directories' `edirs-merge' Merge files common to two directories. `ediff-merge-directories-with-ancestor' `edirs-merge-with-ancestor' Same but using files in a third directory as ancestors. `ediff-merge-revisions' Merge two versions of the file visited by the current buffer. Same but with ancestor. If you want Ediff to be loaded from the very beginning, you should have (require 'ediff) in your .emacs file. Otherwise, Ediff will be loaded automatically when you use one of the above functions, either directly or through the menus. When the above functions are invoked, they prompt the user about the information they need--typically the files or buffers to compare or patch. Ediff tries to be smart about these prompts. For instance, in comparing/merging files, it will offer the visible buffers as defaults. In prompting for files, if the user enters a directory, the previously input file name will be appended to that directory. In addition, if the variable `ediff-use-last-dir' is not `nil', Ediff will offer previously entered directories as defaults (which will be maintained separately for each type of file, A, B, or C). All the above functions use the Unix `diff' utility to find difference regions. They process `diff' output and display it to the user in a convenient form. At present, Ediff understands only the plain output from diff. Options such as `-c' are not supported, nor is the format produced by VMS diff. The functions `ediff-files', `ediff-buffers', `ediff-files3', `ediff-buffers3' first display the coarse, line-based difference regions, as reported by the `diff' program. Since `diff' may report fairly large chunks of text as being different, even though the difference may be localized to just a few words or even to the white space or line breaks, Ediff will further *refine* the regions to indicate which exact words differ. If the only difference is in the white space and line breaks, Ediff will say so. On a color display, fine differences are highlighted with color; on a monochrome display, they are underlined. *Note Highlighting Difference Regions::, to learn how to change that. The functions `ediff-windows-wordwise', `ediff-windows-line-wise', `ediff-regions-wordwise' and `ediff-regions-linewise' do comparison on parts of buffers (which must already exist). Since `ediff-windows-wordwise' and `ediff-regions-wordwise' are intended for relatively small segments of buffers, comparison is done on the basis of words rather than lines. No refinement is necessary in this case. This technique is effective only for relatively small regions (perhaps, up to 100 lines), as these functions have a relatively slow startup. To compare large regions, use ediff-regions-linewise. In this mode, Ediff displays differences as it would if invoked via `ediff-files' or `ediff-buffers.' The functions `ediff-patch-file' and `ediff-patch-buffer' apply a patch to a file or a buffer and then run Ediff on these buffers, displaying the difference regions. Currently, Ediff still doesn't understand multi-file patches (volunteers?). The entry points `ediff-directories', `ediff-merge-directories', etc., provide a convenient interface for comparing and merging files in different directories. The user is presented with Dired-like interface from which one can run a group of related Ediff sessions. Finally, for files under version control, `ediff-revision' lets the user compare versions of the file visited by the current buffer. Moreover, the functions `ediff-directory-revisions', `ediff-merge-directory-revisions', etc., let the user run a group of related Ediff sessions by taking a directory and comparing (or merging) versions of files in that directory (for files that are under version control). File: ediff.info, Node: Commands, Next: Registry of Ediff Sessions, Prev: Major Entry Points, Up: Top Commands ******** All Ediff commands pertinent to a given session are displayed in a quick help window, unless you type `?' to shrink the window to just one line. You can redisplay the help window by hitting `?' again. In this section we comment only on the features that cannot be readily deduced from the quick help window. You can always type `E' in any control window to bring up this manual. Many Ediff commands take numeric prefix arguments. For instance, if you type a number, say 3, and then `j' (ediff-jump-to-difference), Ediff will take you to the 3d difference region. Typing 3 and then `a' (`ediff-diff-to-diff') will copy the 3d difference region from buffer A to buffer B. Hitting `b' does copying in the opposite direction. (In 3-way comparison mode, the commands for copying are `ab', `ba', `ca', etc.) Likewise, 4 followed by `ra' will restore the 4th difference region in buffer A (if it was previously saved as a result of copying from, say, buffer B to A). Without the prefix argument, all commands operate on the current difference region. The total number of differences and the current difference number are always displayed in the mode line of the control window. If, after making changes to buffers A, B, or C, you decide to save them, it is recommended to use `ediff-save-buffer', which is bound to `wa', `wb', and `wc' (`wa' will save buffer A, `wb' saves buffer B, etc.). Typing `wd' saves the output from the `diff' utility to a file, so you can later refer to it. With prefix argument, this command saves the plain output from `diff' (see `ediff-diff-program' and `ediff-diff-options'). Without the argument, it saves customized `diff' output (see `ediff-custom-diff-program' and `ediff-custom-diff-options'), if it is available. Instead of saving it, `diff' output can be *displayed* using the command `D'. Without the prefix argument, it displays the customized `diff' output of the session. With the prefix argument, it displays the plain `diff' output If either of the `diff' outputs is unavailable (because it wasn't generated or the user killed the respective buffer), then Ediff will try to display the other `diff' output. If none is available, a warning is issued. The command `z' suspends the current ediff session. It hides the control buffer and the variants. The easiest way to resume a suspended Ediff session is through the registry of active sessions. *Note Registry of Ediff Sessions::, for details. The command `q' quits the current Ediff session. With a prefix argument, it will ask the user whether to delete the variant buffers. The command `s' is used only for merging. It allows the user to shrink window C to its minimal size, thereby exposing as much of buffers A and B as possible. This command is intended only for temporary viewing. Therefore, Ediff will restore the original window size for buffer C whenever window configuration is changed by the user (on toggling the help, changing the manner in which windows are split, etc.). However, recentering and jumping to a difference does not affect window C. Typing `s' again restores the original size of the merge window. With a positive prefix argument, the command `s' makes the merge window, window C, slightly taller. With `-' or a negative prefix argument, `s' makes window C slightly shorter. In the merge mode, Ediff uses a default variant (one of the two files being merged) when it cannot decide which of the difference regions (that of buffer A or buffer B) should be copied into the merge buffer. A user may decide that the default variant was chosen inappropriately and may wish to change that while merging is in progress. To facilitate this, Ediff has a command, bound to `&', which will cause Ediff to start merging anew beginning with the current difference, using an alternative default variant (the user is asked to type in the new default for merging), which can be either `default-A', `default-B', or `combined'. *Note Merging and diff3::, for details. Such repeated merging affects only difference regions that have default-A/B status, and only if they were not changed with respect to their originals. Another command that is used only for merging is `+'. Its effect is to combine the current difference regions of buffers A and B and put the combination into the merge buffer. *Note Merging and diff3::, specifically, the variables `ediff-combine-diffs' and `ediff-combination-pattern'. Some commands are not bound to any key: `ediff-show-registry' `eregistry' This command brings up the registry of active Ediff sessions. Ediff registry is a useful device that can be used for resuming Ediff sessions when the user switched to some other work before finishing a comparison or merging job. It is also useful for switching between multiple active Ediff sessions that are run at the same time. The function `eregistry' is an alias for `ediff-show-registry'. `ediff-toggle-multiframe' Changes the display from the multi-frame mode (where the quick help window is in a separate frame) to the single-frame mode (where all Ediff buffers share the same frame), and vice versa. `ediff-revert-buffers-then-recompute-diffs' This is useful when, after making changes, you decided to make a fresh start, or if at some point you changed the files being compared but want to discard any changes to comparison buffers that were done since then. This command will ask for confirmation before reverting files. With a prefix argument, it will revert files without asking. `ediff-profile' Ediff has an admittedly primitive (but useful) facility for profiling Ediff's commands. Users should not be concerned with this feature, unless they are willing to put time into improving the efficiency of Ediff. The function `ediff-profile' toggles profiling of ediff commands. File: ediff.info, Node: Registry of Ediff Sessions, Next: Session Groups, Prev: Commands, Up: Top Registry of Ediff Sessions ************************** Ediff maintains a registry of all its invocations that are still *active*. This feature is very convenient for switching among active Ediff sessions or for quickly restarting a suspended Ediff session. The focal point of this activity is a buffer called **Ediff Registry**. You can display this buffer by typing `R' in any Ediff Control Buffer or Session Group Buffer (*note Session Groups::.), or by typing `M-x eregistry' into the Minibuffer. The latter would be the fastest way to bring up the registry buffer if no control or group buffer is displayed in any of the visible Emacs windows. If you are in a habit of running multiple long Ediff sessions and often need to suspend, resume, or switch between them, it may be a good idea to have the registry buffer permanently displayed in a separate, dedicated window. The registry buffer has several convenient key bindings. For instance, clicking mouse button 2 or typing `RET' or `v' over any session record resumes that session. Session records in the registry buffer provide a fairly complete description of each session, so it is usually easy to identify the right session to resume. Other useful commands are bound to `SPC' (next registry record) and `DEL' (previous registry record). There are other commands as well, but you don't need to memorize them, since they are listed at the top of the registry buffer. File: ediff.info, Node: Session Groups, Next: Remote and Compressed Files, Prev: Registry of Ediff Sessions, Up: Top Session Groups ************** Several major entries of Ediff perform comparison and merging on directories. On entering `ediff-directories', `ediff-directories3', `ediff-merge-directories', `ediff-merge-directories-with-ancestor', `ediff-directory-revisions', `ediff-merge-directory-revisions', or `ediff-merge-directory-revisions-with-ancestor', the user is presented with a Dired-like buffer that lists files common to the directories involved along with their sizes. (The list of common files can be further filtered through a regular expression, which the user is prompted for.) We call this buffer *Session Group Panel* because all Ediff sessions associated with the listed files will have this buffer as a common focal point. Clicking button 2 or typing `RET' or `v' over a record describing files invokes Ediff in the appropriate mode on these files. You can come back to the session group buffer associated with a particular invocation of Ediff by typing `M' in Ediff control buffer of that invocation. Many commands are available in the session group buffer; some are applicable only for certain types of work. The relevant commands are always listed at the top of each session group buffer, so there is no need to memorize them. In directory comparison or merging, a session group panel displays only the files common to all directories involved. The differences are kept in a separate buffer and are conveniently displayed by typing `D' to the corresponding session group panel. Thus, as an added benefit, Ediff can be used to compare the contents of up to three directories. Session records in session group panels are also marked with `+', for active sessions, and with `-', for finished sessions. Sometimes, it is convenient to exclude certain session records from a group. Usually this happens when the user doesn't intend to run Ediff of certain files in the group, and the corresponding session records just add clutter to the session group buffer. To help alleviate this problem, the user can type `x' to mark a session as a candidate for exclusion and `x' to actually hide the marked sessions. There actions are reversible: with a prefix argument, `h' unmarks the session under the cursor, and `x' brings the hidden sessions into the view (`x' doesn't unmark them, though, so the user has to explicitly unmark the sessions of interest). Group sessions also understand the command `m', which marks sessions for future operations (other than hiding) on a group of sessions. At present, the only such group-level operation is the creation of a multi-file patch. A multi-file patch is a concatenated output of several runs of the Unix `diff' command (some versions of `diff' let you create a multi-file patch in just one run). In a session group buffer created in response to `ediff-directories' or `ediff-directory-revisions', the user can type `P' to create a multi-file patch of marked sessions (which must be marked using the `m' command). Ediff then will display a buffer containing the patch. In an `ediff-directories' session, it is enough to just mark the requisite sessions. In `ediff-directory-revisions' revisions, the marked sessions must also be active, or else Ediff will refuse to produce a multi-file patch. This is because, in the latter-style sessions, there are many ways to create diff output, and it is easier to handle by running Ediff on the inactive sessions. File: ediff.info, Node: Remote and Compressed Files, Next: Customization, Prev: Session Groups, Up: Top Remote and Compressed Files *************************** Ediff works with remote, compressed, and encrypted files. Ediff supports ange-ftp.el, jka-compr.el, uncompress.el and crypt++.el, but it may work with other similar packages as well. This means that you can compare files residing on another machine, or you can apply a patch to a file on another machine (even the patch itself can be a remote file!). When patching compressed or remote files, Ediff does not rename the source file (unlike what the `patch' utility would usually do). Instead, the source file retains its name and the result of applying the patch is placed in a temporary file that has the suffix `_patched' attached. Generally, this applies to files that are handled using black magic, such as special file handlers (ange-ftp and some compression and encryption packages all use this method). Regular files are treated by the `patch' utility in the usual manner, i.e., the original is renamed into `source-name_orig' and the result of the patch is placed into the file source-name. (Ediff uses `_orig' instead of the usual `.orig' to placate systems like VMS.) File: ediff.info, Node: Customization, Next: Credits, Prev: Remote and Compressed Files, Up: Top Customization ************* Ediff has a rather self-explanatory interface, and in most cases the user won't need to change anything. However, should the need arise, there are extensive facilities to change the default behavior. Most of the customization can be done by setting various variables in the `.emacs' file. Some customization (mostly window-related customization and faces) can be done by putting appropriate lines in `.Xdefaults', `.xrdb', or whatever X resource file is in use. With respect to the latter, it is important to be aware that the X resource for Ediff customization is `Ediff', *not* `emacs'. *Note Window and Frame Configuration::, *Note Highlighting Difference Regions::, for further details. Please also refer to Emacs manual for the information on how to set Emacs X resources. * Menu: * Hooks:: Customization via the hooks. * Quick Help:: How to customize Ediff's quick help feature. * Window and Frame Configuration:: Controling the way Ediff displays things. * Selective Browsing:: Advanced browsing through difference regions. * Highlighting Difference Regions:: Control over highlighting. * Narrowing:: Comparing regions, windows, etc. * Refinement of Difference Regions:: How to control the refinement process. * Patch and Diff Programs:: Changing the utilities that compute differences and apply patches. * Merging and diff3:: How to customize Ediff in its Merge Mode. * Support for Version Control:: Changing the version control package. You are not likely to do that. * Customizing the Mode Line:: Changing the look of the mode line in Ediff. * Miscellaneous:: Other customization. * Notes on Heavy-duty Customization:: Customization for the gurus. File: ediff.info, Node: Hooks, Next: Quick Help, Prev: Customization, Up: Customization Hooks ===== The bulk of customization can be done via the following hooks: `ediff-load-hooks' Can be used to change defaults after Ediff is loaded. These hooks are executed right after the default bindings are set. `ediff-keymap-setup-hooks' Can be used to alter bindings in Ediff's keymap. These hooks are called right after the default bindings are set. `ediff-before-setup-windows-hooks' `ediff-after-setup-windows-hooks' Called before/after Ediff sets up its window configuration. Can be used to save the configuration that existed before Ediff starts or for whatever other purposes. `ediff-suspend-hooks' `ediff-quit-hooks' Can be used to set desired window configurations, delete files Ediff didn't want to clean up after exiting, etc. By default, `ediff-quit-hooks' is set to a function, `ediff-cleanup-mess', which cleans after Ediff, as appropriate in most cases. It is rather unlikely that the user will want to change it. However, the user may want add other hooks to `ediff-quit-hooks', either before or after `ediff-cleanup-mess' (see the documentation for `add-hook' in Emacs manual on how to do this). One should be aware that hooks executing before `ediff-cleanup-mess' start in `ediff-control-buffer;' they should also leave `ediff-control-buffer' as the current buffer when they finish. Hooks that are executed after `ediff-cleanup-mess' should expect the current buffer be either buffer A or buffer B. `ediff-cleanup-mess' doesn't kill the buffers being compared or merged (see `ediff-cleanup-hooks', below). `ediff-cleanup-hooks' Default is `nil'. Hooks to run just before running `ediff-quit-hooks'. This is a good place to do various cleanups, such as deleting the variant buffers. Ediff provides a function, `ediff-janitor', as one such possible hook, which the user can `add-hooks' to `ediff-cleanup-hooks'. This function kills buffers A, B, and, possibly, C, if these buffers aren't modified. In merge jobs, buffer C is never deleted. However, the side effect of using this function is that you may not be able to compare the same buffer in two separate Ediff sessions: quitting one of them will delete this buffer in another session as well. `ediff-before-setup-control-frame-hooks' `ediff-after-setup-control-frame-hooks' Can be used to relocate Ediff control frame when Ediff runs in a multiframe mode (i.e., when the control buffer is in its own dedicated frame). Be aware that many variables that drive Ediff are local to Ediff Control Panel (`ediff-control-buffer'), which requires special care in writing these hooks. Take a look at `ediff-default-suspend-hook' and `ediff-default-quit-hook' to see what's involved. `ediff-startup-hooks' Last hook called after Ediff starts up. `ediff-select-hooks' Called after Ediff selects the next difference region. `ediff-unselect-hooks' Called after Ediff unselects the current difference region. `ediff-prepare-buffer-hooks' Hooks executed for each Ediff buffer (A, B, C) right after these buffers are arranged. `ediff-display-help-hooks' Ediff executes these hooks each time after setting up the help message. Can be used to alter the help message for custom packages that run on top of Ediff. `ediff-mode-hooks' Called just after Ediff mode is set up in the control buffer. This is done before any Ediff window is created. One can use it to set local variables that alter the look of the display. `ediff-registry-setup-hooks' Hooks run after setting up the registry for all active Ediff session. *Note Session Groups::, for details. `ediff-session-group-setup-hooks' Hooks run after setting up a control panel for a group of related Ediff sessions. *Note Session Groups::, for details. File: ediff.info, Node: Quick Help, Next: Window and Frame Configuration, Prev: Hooks, Up: Customization Quick Help ========== Ediff provides quick help using its control panel window. Since this window takes a fair share of the screen real estate, you can toggle it off by hitting `?'. The control window will then shrink to just one line and a mode line, displaying a short help message. The variable `ediff-prefer-long-help-message' tells Ediff whether the user wants the short message initially or the long one. By default, it is set to `nil', meaning that the short message will be shown on startup. Set this to `t', if you want Ediff to start with the long message. If you want to change the appearance of the help message on a per-buffer basis, you must use `ediff-startup-hooks' to change the value of the variable `ediff-help-message', which is local to `ediff-control-buffer'. File: ediff.info, Node: Window and Frame Configuration, Next: Selective Browsing, Prev: Quick Help, Up: Customization Window and Frame Configuration ============================== On a non-windowing display, Ediff sets things up in one frame, splitting it between a small control window and the windows for buffers A, B, and C. The split between these windows can be horizontal or vertical, which can be changed interactively by typing `|' while the cursor is in the control window. On a window display, Ediff sets up a dedicated frame for Ediff Control Panel and then it chooses windows as follows: If one of the buffers is invisible, it is displayed in the currently selected frame. If a buffer is visible, it is displayed in the frame where it is visible. If, according to the above criteria, the two buffers fall into the same frame, then so be it--the frame will be shared by the two. The same algorithm works when you hit `C-l' (`ediff-recenter'), `p' (`ediff-previous-difference'), `n' (`ediff-next-difference'), etc. The above behavior also depends on whether the current frame is splittable, dedicated, etc. Unfortunately, the margin is too small to present this remarkable algorithm. The bottom line of all this is that you can compare buffers in one frame or in different frames. The former is done by default, while the latter can be achieved by arranging buffers A, B (and C, if applicable) to be seen in different frames. Ediff respects these arrangements, automatically adapting itself to the multi-frame mode. Ediff uses the following variables to set up its control panel (a.k.a. control buffer, a.k.a. quick help window): `ediff-control-frame-parameters' The user can change or augment this variable including the font, color, etc. The X resource name of Ediff Control Panel frames is `Ediff'. Under X-windows, you can use this name to set up preferences in your `~/.Xdefaults', `~/.xrdb', or whatever X resource file is in use. Usually this is preferable to changing `ediff-control-frame-parameters' directly. For instance, you can specify in `~/.Xdefaults' where the control frame is to be sitting on the screen using the resource `Ediff*geometry'. In general, any X resource pertaining the control frame can be reached via the prefix `Ediff*'. `ediff-control-frame-position-function' The prefered way of specifying the position of the control frame is by setting the variable `ediff-control-frame-position-function' to an appropriate function. The default value of this variable is `ediff-make-frame-position'. This function places the control frame in the vicinity of the North-East corner of the frame displaying buffer A. The following variables can be used to adjust the location produced by `ediff-make-frame-position' and for related customization. `ediff-narrow-control-frame-leftward-shift' Specifies the number of characters for shifting the control frame from the rightmost edge of frame A when the control frame is displayed as a small window. `ediff-wide-control-frame-rightward-shift' Specifies the rightward shift of the control frame from the left edge of frame A when the control frame shows the full menu of options. `ediff-control-frame-upward-shift' Specifies the number of pixels for the upward shift of the control frame. `ediff-prefer-iconified-control-frame' If t, the control frame becomes iconified automatically when the quick help message is toggled off. This saves valuable real estate on the screen. Toggling help back will deiconify the control frame. To start Ediff with an iconified Control Panel, you should set this variable to t and `ediff-prefer-long-help-message' to nil. This behavior is useful only in Emacs (not in XEmacs) and only if the window manager is TWM or a derivative. If you truly and absolutely dislike the way Ediff sets up windows and if you cannot change this via frame parameters, the last resort is to rewrite the function `ediff-setup-windows'. However, we believe that detaching Ediff Control Panel from the rest and making it into a separate frame offers an important opportunity by allowing you to iconify that frame. Under Emacs, the icon will usually accept all of the Ediff commands, but will free up valuable real estate on your screen (this may depend on the window manager, though). Iconifying won't do any good under XEmacs since XEmacs icons are not sensitive to keyboard input. The saving grace is that, even if not iconified, the control frame is very small, smaller than some icons, so it does not take much space in any case. The following variable controls how windows are set up. `ediff-window-setup-function' The multiframe setup is achieved via `ediff-setup-windows-multiframe' function, which is a default on windowing displays. The plain setup, one where all windows are always in one frame, is done via `ediff-setup-windows-plain', which is the default on a non-windowing display (or in an xterm window). In fact, under Emacs, you can switch freely between these two setups by executing the command `ediff-toggle-multiframe' using the Minibuffer. If you don't like any of these setups, write your own function. See the documentation for `ediff-window-setup-function' for the basic guidelines. However, writing window setups is not easy, so before embarking on this job you may want to take a close look at `ediff-setup-windows-plain' and `ediff-setup-windows-multiframe'. The user can run multiple Ediff sessions at once, by invoking Ediff several times without exiting previous Ediff sessions. Different sessions may even operate on the same pair of files. Each session would have its own Ediff Control Panel and all the regarding a particular session is local to the associated control panel buffer. You can switch between sessions by suspending one session and then switching to another control panel. (Different control panel buffers are distinguished by a numerical suffix, e.g., Ediff Control Panel<3>.) File: ediff.info, Node: Selective Browsing, Next: Highlighting Difference Regions, Prev: Window and Frame Configuration, Up: Customization Selective Browsing ================== Sometimes it is convenient to be able to step through only some difference regions, those that satisfy certain conditions, and to ignore all others. The commands `#f' and `#h' let the user specify regular expressions to control the way Ediff skips to the next or previous difference. Typing `#f' lets one specify regular expressions for each buffer, regexp-A, regexp-B, and regexp-C. Ediff will then start stepping through only those difference regions where the region in buffer A matches regexp-A and/or the region in buffer B matches regexp-B, etc. Whether `and' or `or' will be used depends on how the user responds to a prompt. Similarly, using `#h', one specifies expressions that match difference regions to be ignored while stepping through the differences. That is, if the buffer A part matches regexp-A, the buffer B part matches regexp B and (if applicable) buffer-C part matches regexp-C, then the region will be ignored by the commands `n'/`SPC' (`ediff-next-difference') and `p'/`DEL' (`ediff-previous-difference') commands. Hitting `#f' and `#h' toggles selective browsing on/off. Note that selective browsing affects only `ediff-next-difference' and `ediff-previous-difference', i.e., the commands invoked by typing `n'/`SPC' and `p'/`DEL'. You can still jump directly (using `j' or `ga'/`gb'/`gc') to any numbered difference. Also, it should be understood, that `#f' and `#h' do not change the position of the point in the buffers. The effect of these commands is seen only when the user types `n' or `p', i.e., when Ediff is told to jump to the next or previous difference. Users can supply their own functions to specify how Ediff should do selective browsing. To change the default Ediff function, add a function to `ediff-load-hooks' which will do the following assignments: (fset ediff-hide-regexp-matches 'your-hide-function) (fset ediff-focus-on-regexp-matches 'your-focus-function) *Useful hint*: To specify a regexp that matches everything, don't simply type `RET' in response to a prompt. Typing `RET' tells Ediff to accept the default value, which may not be what you want. Instead, you should enter something like ``^'' or ``$'' -- which matches every line. If the user does not remember if selective browsing is in effect and which regexps are being used, the status command, `i', will supply the requisite information. In addition to the ability to ignore regions that match regular expressions, Ediff can be ordered to start skipping over certain `inessential' regions. This is controlled by the variable `ediff-ignore-similar-regions' If `t', causes Ediff to skip over difference regions that deemed inessential, i.e., where the only differences are those in the white space and newlines. *Note*: In order for this feature to work, auto-refining of difference regions must be on, since otherwise Ediff won't know if there are fine differences between regions. Under X, auto-refining is a default, but it is nixed on dumb terminals or in Xterm windows. Therefore, in a non-windowing environment, the user must explicitly turn auto-refining on (e.g., by typing `@'). *Caution*: If many inessential regions appear in a row, Ediff may take a long time to jump to the next region because it has to compute fine differences of all intermediate regions. File: ediff.info, Node: Highlighting Difference Regions, Next: Narrowing, Prev: Selective Browsing, Up: Customization Highlighting Difference Regions =============================== The following variables control the way Ediff highlights difference regions. `ediff-before-flag-bol' `ediff-after-flag-eol' `ediff-before-flag-mol' `ediff-after-flag-mol' The above are ASCII strings that mark the beginning and the end of the differences found in files A, B, and C. Ediff uses different flags to highlight regions that begin/end at the beginning/end of a line or in a middle of a line. `ediff-current-diff-face-A' `ediff-current-diff-face-B' `ediff-current-diff-face-C' Ediff uses these faces to highlight current differences on X displays. These and subsequently described faces can be set either in `.emacs' or in `.Xdefaults'. The X resource for Ediff is `Ediff', *not* `emacs'. Please refer to Emacs manual for the information on how to set X resources. `ediff-fine-diff-face-A' `ediff-fine-diff-face-B' `ediff-fine-diff-face-C' Faces used to show the fine differences between the current differences regions in buffers A, B, and C, respectively. `ediff-even-diff-face-A' `ediff-even-diff-face-B' `ediff-even-diff-face-C' `ediff-odd-diff-face-A' `ediff-odd-diff-face-B' `ediff-odd-diff-face-C' Non-current difference regions are displayed using these alternating faces. The odd and the even faces are actually identical on monochrome displays, because without colors options are limited. So, Ediff uses italics to highlight non-current differences. `ediff-highlight-all-diffs' Indicates whether--on a window system--the user wants differences to be marked using ASCII strings (like on a dumb terminal) or using colors and highlighting. Normally, Ediff highlights all differences, but the selected difference is highlighted more visibly. One can cycle through various modes of highlighting by hitting `h'. By default, Ediff starts in the mode where all difference regions are highlighted. If you prefer to start in the mode where unselected differences are not highlighted, you should set `ediff-highlight-all-diffs' to `nil'. Typing `h' restores highlighting of all differences. Ediff lets you switch between the two modes of highlighting. That is, you can switch interactively from highlighting using faces to highlighting using ASCII flags, and back. Of course, switching has effect only under a windowing system. On a dumb terminal or in an xterm window, the only available option is highlighting with ASCII flags. If you want to change the above variables, they must be set *before* Ediff is loaded. There are two ways to change the default setting for highlighting faces: either change the variables, as in (setq ediff-current-diff-face-A 'bold-italic) or (setq ediff-current-diff-face-A (copy-face 'bold-italic 'ediff-current-diff-face-A)) or modify the defaults selectively: (add-hook 'ediff-load-hooks (function (lambda () (set-face-foreground ediff-current-diff-face-B "blue") (set-face-background ediff-current-diff-face-B "red") (make-face-italic ediff-current-diff-face-B)))) You may also want to take a look at how the above faces are defined in the source code of Ediff. *Note*: it is not recommended to use `internal-get-face' (or `get-face' in XEmacs) when defining Ediff's faces, since this may cause problems when there are several frames with different font sizes. Instead, use `copy-face', `set-face-*', or `make-face-*' as shown above. File: ediff.info, Node: Narrowing, Next: Refinement of Difference Regions, Prev: Highlighting Difference Regions, Up: Customization Narrowing ========= If buffers being compared are narrowed at the time of invocation of Ediff, `ediff-buffers' will preserve the narrowing range. However, if `ediff-files' is invoked on the files visited by these buffers, narrowing will be turned off, since we assume that the user wants to compare the entire files. Invocation of `ediff-regions-wordwise/linewise' and `ediff-windows-wordwise/linewise' will cause Ediff to set new narrowing ranges (corresponding to the windows being compared). However, the old ranges are preserved and can be restored by typing `%'. The original ranges will be also restored on quitting Ediff. Two variables control the behavior of `ediff-windows-wordwise/linewise', `ediff-regions-wordwise/linewise' with respect to narrowing: `ediff-start-narrowed' If `t', Ediff will narrow the display to the appropriate range if it is invoked as `ediff-windows-wordwise/linewise' or `ediff-regions-wordwise/linewise.' If `nil', narrowing will not take place. However, the user can still toggle narrowing on and off by typing `%'. `ediff-quit-widened' Controls whether on exiting Ediff should restore the visibility range that existed before the current invocation. File: ediff.info, Node: Refinement of Difference Regions, Next: Patch and Diff Programs, Prev: Narrowing, Up: Customization Refinement of Difference Regions ================================ Ediff has variables to control the way fine differences are highlighted. This feature give the user control over the process of refinement. Note that refinement ignores spaces, tabs, and newlines. `ediff-auto-refine' The default is `on', which means that fine differences within regions will be highlighted automatically. On a slow machine, automatic refinement may be painful. In that case, the user can toggle auto-refining on or off (or nix it completely) by hitting `@'. When auto-refining is off, fine differences will be shown only for regions for which these differences have been computed and saved before. If auto-refining is nixed, fine differences will not be shown at all. Hitting `*' will compute and redisplay fine differences for the current difference region, regardless of the status auto-refining. `ediff-auto-refine-limit' If auto-refining is on, this variable limits the size of the regions to be auto-refined. This guards against the possible slow-down that may be caused by extraordinary large difference regions. The user can always refine the current region by typing `*'. `ediff-forward-word-function' Gives the user control over how fine differences are computed. The value must be a lisp function that determines how the current difference region should be split into words. Fine diferences are computed by first splitting the current difference region into words and then passing this along to `ediff-diff-program'. For the default `ediff-forward-word-function' (which is `ediff-forward-word'), a word is a string consisting of letters, `-', or `_'; a string of punctuation symbols; a string of digits, or a string consisting of symbols that are neither space, nor a letter. This default behavior is controlled by four variables: `ediff-word-1', ..., `ediff-word-4'. See the on-line documentation for these variables and for the function `ediff-forward-word' for an explanation of how to modify these variables. Sometimes, when a region has too many differences between the variants, highlighting of fine differences stands in the way, especially on color displays. If that is the case, the user can type `*' with a negative prefix argument, which would unhighlight fine differences for the current region. To unhighlight fine differences in all `diff' regions, use the command `@'. Repeated typing of this key cycles through three different states: auto-refining, no-auto-refining, and no-highlighting of fine differences. File: ediff.info, Node: Patch and Diff Programs, Next: Merging and diff3, Prev: Refinement of Difference Regions, Up: Customization Patch and Diff Programs ======================= The next group of variables determines the programs to be used for applying patches and for computing the main difference regions (not the fine difference regions): `ediff-patch-program' `ediff-diff-program' `ediff-diff3-program' Specify the functions that produce differences and do patching. `ediff-patch-options' `ediff-diff-options' `ediff-diff3-options' Specify which options to pass to the above utilities. It is unlikely that you would want to change these. However, sometimes you may want to tell `diff' to ignore spaces and such. Use the option `-w' for that. Diff has several other useful options (type `man diff' to find out). However, Ediff does not let you use the option `-c', as it doesn't recognize this format yet. If you need to save the output from `diff' in a special format, Ediff lets you specify "custom" `diff' format using the following two variables: `ediff-custom-diff-program' The output generated by `ediff-custom-diff-program' (which doesn't even have to be a Unix-style `diff'!) is not used by Ediff. It is provided exclusively so that the user could save if using the function `ediff-save-buffer' (normally bound to `wd') and later refer to it. However, Ediff is not the preferred way of producing `diff' output in Emacs. Unless you also intend to use Ediff for browsing through the diff'ed files, `M-x diff' may be a faster way to generate output from `diff'. `ediff-custom-diff-options' Specifies the options to pass to `ediff-custom-diff-program'. *Beware of VMS Diff*: The output from VMS Diff is not yet supported. Instead, make sure some implementation of Unix diff, such as gnudiff, is used.